<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Upgrading Instructions : DataMapper ORM - User Guide</title>

<link rel="shortcut icon" type="image/png" href="../images/favicon.png" />
<link rel="stylesheet" type="text/css" media="all" href="../css/userguide.css" />
<link rel="alternate" type="application/rss+xml" title="Datamapper ORM Updates Feed" href="/rss.xml" />

<meta http-equiv="expires" content="-1" />
<meta http-equiv= 'pragma' content="no-cache" />
<meta name="robots" content="all" />

</head>

<body>

<!-- START NAVIGATION -->
<div id="nav"><div id="nav_inner"></div></div>
<div id="nav2"><a name="top">&nbsp;</a><a id="nav_toggle" href="#"><img src="../images/nav_toggle_darker.jpg" width="154" height="43" border="0" title="Toggle Table of Contents" alt="Toggle Table of Contents" /></a></div>
<div id="masthead">
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td><h1>DataMapper ORM</h1></td>
<td id="breadcrumb_right"><a href="toc.html">Table of Contents Page</a></td>
</tr>
</table>
</div>
<!-- END NAVIGATION -->

<!-- START BREADCRUMB -->
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td id="breadcrumb">
<a href="/">Datamapper ORM Home</a> &nbsp;&#8250;&nbsp;
<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
Upgrading Instructions
</td>
</tr>

</table>
<!-- END BREADCRUMB -->

<br clear="all" />


<!-- START CONTENT -->
<div id="content">


<h1>Upgrading Instructions</h1>
<p>Upgrading requires replacing a few files, and sometimes updating your configuration.  You can upgrade from a previous version of Datamapper ORM, from <a href="#Upgrade.DMZ">DMZ</a>, or <a href="#Upgrade.DataMapper">the original DataMapper</a>.</p>

<div class="highlight">
<h3>All versions</h3>
<ul>
	<li>Overwrite <var>application/libraries/datamapper.php</var>.</li>
	<li>Copy any new extensions in <var>application/datamapper</var> that you would like to use.
		<div class="note">
			<p>Some extensions may require additional <b>views</b>, <b>libraries</b>, <b>helpers</b>, or other items to function correctly.  Please <a href="extlist.html">check the extensions</a> you plan on using.</p>
		</div>
	</li>
	<li>If you are using the <a href="prodcache.html">Production Cache</a>, please clear it, and possibly even disable it until you have tested the new version.</li>
</ul>
<p>Then look below for additional, specific changes for each version.</p>
</div>

<h2>Upgrading from a previous version of DataMapper ORM</h2>

<p class="note">You can determine which version of Datamapper ORM you are using by looking at the top of <var>application/libraries/datamapper.php</var></p>

<h3>From 1.8.1 to 1.8.2</h3>
<ul>
	<li>DataMapper 1.8.2 is mainly a bugfix release, altough it does add some new features. One important feature is support for CodeIgniter 2.0.3 and newer (including Reactor).</li>
	<li>To use this version, you need to install the DataMapper bootstrap in your index.php file:
		<pre style="background-color:#B4FFBB;font-weight:bold;">/*
 * --------------------------------------------------------------------
 * LOAD THE DATAMAPPER BOOTSTRAP FILE
 * -------------------------------------------------------------------- *
 */
require_once APPPATH.'third_party/datamapper/bootstrap.php';</pre>
Place this line of code at the end of your applications index.php file, just <strong>ABOVE</strong> the CodeIgniter bootstrap file!
	</li>
	<li><p class="important" style="color:red;">DataMapper 1.8.2. only works on CodeIgniter version 2.0.3. and above!</p></li>
</ul>


<h3>From 1.8.0 to 1.8.1</h3>
<ul>
	<li>DataMapper 1.8.1 is mainly a bugfix release, altough it does add some new features. There are no additional upgrade instructions for this release.</li>
	<li><p class="important" style="color:red;">DataMapper 1.8.1. only works on CodeIgniter version 2.0.2. and below!</p></li>
</ul>

<h2 id="Upgrade.DMZ">Upgrading from Datamapper DMZ "OverZealous" Edition</h2>

<h3>From 1.7.1 to 1.8.0</h3>
<ul>
	<li>DataMapper 1.8.0 is mainly a bugfix release, altough it does add some new features. There are no additional upgrade instructions for this release.</li>
</ul>

<h3>From 1.7.0 to 1.7.1</h3>
<ul>
	<li>Make sure you replace all extensions, since they now work with <var><u>get_iterated</u></var>!</li>
	<li>If you had previously overridden <var><u>_assign_libraries</u></var>, you will need to override <var><u>_dmz_assign_libraries</u></var> instead.</li>
	<li>Make sure you check out the new <a href="getalt.html#When.To.Use.Get.Iterated">When To Use Get Iterated</a> section for getting the most out of Datamapper ORM 1.7.</li>
</ul>

<h3>From 1.6.2 to 1.7.0</h3>
<ul>
	<li>Replace <var>application/helpers/inflector_helper</var> with the updated version in Datamapper ORM.</li>
	<li>If you want to use the new <a href="localize.html">localization</a> functionality, you need to add <var><i>lang_file_format</i></var> to your <a href="config.html">config file</a>.</li>
	<li>
		A minor "gotchya" with the new localization (even if it is not explicitly enabled) is that you may find that relationships
		have a <var><i>$validation</i></var> entry when they didn't before.
		(This occurs when there is a language key of the form <dfn>${model}_${relationship}</dfn>.)<br/>
		If this causes an issue, you can forcibly disable localization by setting the config option <var><i>field_label_lang_format</i></var> to something nonsensical, like <dfn>'DO_NOT_USE_LOCALIZATION'</dfn>.
	</li>
	<li>It is recommended, but optional, that you modify your <a href="functions.html#select_func.AR.Bug">CodeIgniter installation</a> to improve compatibility.</li>
	<li>Many methods and variables have been made private or protected.  You <strong>will</strong> get class errors if you have overloaded these in the past.  Some of the private variables have also been renamed.</li>
	<li><p>These new <a href="reservednames.html">reserved names</a> have been added, and should not be overwritten:</p>
		<table class="tableborder" cellspacing="1" cellpadding="0" border="0">
			<tr>
				<th colspan="4">New Functions</th>
			</tr>
			<tr>
				<td>get_iterated</td>
				<td>get_paged</td>
				<td>get_paged_iterated</td>
				<td>get_raw</td>
			</tr>
			<tr>
				<td>count_distinct</td>
				<td>result_count</td>
				<td>{query}_field_func</td>
				<td>_add_to_select_directly</td>
			</tr>
			<tr>
				<td>localize_field</td>
				<td>localize_by_model</td>
				<td colspan="2">_get_generated_timestamp</td>
			</tr>
			<tr>
				<td>_clear_after_query</td>
				<td>_handle_related</td>
				<td colspan="2">_process_special_query_clause</td>
			</tr>
			<tr>
				<th colspan="4">New Variables</th>
			</tr>
			<tr>
				<td>$timestamp_format</td>
				<td>$_dmz_config_defaults</td>
				<td>$_field_tracking</td>
				<td>&nbsp;</td>
			</tr>
			<tr>
				<td>$lang_file_format</td>
				<td colspan="2">$field_label_lang_format</td>
				<td>&nbsp;</td>
			</tr>
			<tr>
				<th colspan="4">Renamed Variables</th>
			</tr>
			<tr>
				<td>$_instantiations</td>
				<td>$_query_related</td>
				<td>$_validated</td>
				<td>&nbsp;</td>
			</tr>
		</table>
		<br />
	</li>
	<li>As this is a significant update, you really should look at the <a href="changelog.html">Change Log</a>, to see how the new features can benefit you.</li>
</ul>

<p>&nbsp;</p>

<h3>From 1.6.1 to 1.6.2</h3>
<ul>
	<li>Bugfix release, no changes necessary.</li>
</ul>

<h3>From 1.6.0 to 1.6.1</h3>
<ul>
	<li>If you used the example <var>application/config/datamapper.php</var> configuration file, change the value of <var><i>$db_params</i></var> from <dfn>NULL</dfn> to <dfn>''</dfn>.</li>
</ul>

<h3>From 1.5.4 to 1.6.0</h3>
<ul>
	<li>
		Due to the new DB mapping, you may experience errors with custom code that expected <var><b>$this</b></var><kbd>-&gt;</kbd><var>db</var> to be shared across models.
		<div class="highlight">
			<p>If you don't need subqueries or <var><u>include_related_count</u></var>, then you can set <var><i>$db_params</i></var> to <dfn>FALSE</dfn> and Datamapper ORM will revert to the shared DB.</p>
			<p>Note, however, that other changes have been made that may cause issues with a shared DB class.</p>
		</div>
	</li>
	<li><p>These new <a href="reservednames.html">reserved names</a> have been added, and should not be overwritten:</p>
		<table class="tableborder" cellspacing="1" cellpadding="0" border="0">
			<tr>
				<th colspan="4">Functions</th>
			</tr>
			<tr>
				<td>func</td>
				<td>get_sql</td>
				<td>include_related_count</td>
				<td>{query}_subquery</td>
			</tr>
			<tr>
				<td>{query}_func</td>
				<td>{query}_related_subquery</td>
				<td>_process_function_arg</td>
				<td>_parse_subquery_object</td>
			</tr>
			<tr>
				<th colspan="4">Variables</th>
			</tr>
			<tr>
				<td>$db_params</td>
				<td>$instantiations</td>
				<td>&nbsp;</td>
				<td>&nbsp;</td>
			</tr>
		</table>
		<br />
	</li>
	<li>As this is a significant update, you may want to look at the <a href="changelog.html">Change Log</a>, to see how the new features can benefit you.</li>
</ul>
<p>&nbsp;</p>

<h3>From 1.5.3 to 1.5.4</h3>
<ul>
	<li>Bugfix release, no changes necessary.</li>
</ul>

<p>&nbsp;</p>

<h3>From 1.5.2 to 1.5.3</h3>
<ul>
	<li>If you were using the private method <var><u>_to_object</u></var>, it works completely differently now.</li>
</ul>

<p>&nbsp;</p>

<h3>From 1.5.1 to 1.5.2</h3>
<ul>
	<li>
		<p class="important">The default behavior for indexing the <var><i>all</i></var> array has been changed.</p>
		<p>If you are getting duplicate results in your queries, you have two options:</p>
		<ol>
			<li>Update your queries to include <strong>DISTINCT</strong> whenever possible.  This is the recommended option.</li>
			<li>
				There is a new <a href="config.html">config option</a>, <var><i>all_array_uses_ids</i></var>.
				Set this to <dfn>TRUE</dfn> to restore the original behavior.
			</li>
		</ol>
	</li>
</ul>

<p>&nbsp;</p>

<h3>From 1.4.x to 1.5.1</h3>
<ul>
	<li>
		<p class="highlight">
			Two of the extensions have been renamed, due to the new extension prefix support.<br/>
			I highly recommend you update your code, because the <b>old names are no longer be supported</b>.
		</p>
		<p>You will need to replace all instances of <dfn>'arrayutils'</dfn> with <dfn>'array'</dfn>, and <dfn>'csvutils'</dfn> with <dfn>'csv'</dfn>.</p>
	</li>
	<li>Replace <strong>all</strong> of the included extensions, and remove the old <var>arrayutils.php</var> and <var>csvutils.php</var>.</li>
</ul>

<p>&nbsp;</p>

<h2>Older Upgrades</h2>
<p>You can find upgrade instructions for older versions by downloading a previous version of DataMapper.  Version 1.6.2 contains <b>all</b> of the upgrades through 1.6.2.</p>

<p>&nbsp;</p>

<h2 id="Upgrade.DataMapper">Upgrading from the original DataMapper</h2>

<p>If you are upgrading from the original DataMapper, these are the steps you should take.</p>

<ol>
	<li>Update your <var>application/config/datamapper.php</var> file, as <a href="config.html">there are a few new items</a>.</li>
	<li>Overwrite <var>application/libraries/datamapper.php</var>.</li>
	<li>Overwrite <var>application/language/english/datamapper.php</var>.</li>
	<li>Optionally, upload the <var>application/datamapper</var> directory to your CodeIgniter <kbd>application</kbd> folder, to enable the use of extensions.</li>
	<li>Look over the upgrade information above, to see if you are using any hacks or tricks that may be broken by Datamapper ORM's new features.</li>
	<li>After reading through this manual, you may want to adopt many of the new features throughout your code!</li>
</ol>

</div>
<!-- END CONTENT -->


<div id="footer">
<p>
<span id="footer_previous">Previous Topic:&nbsp;&nbsp;<a href=""></a>
&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;</span>
<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
<a href="../index.html">User Guide Home</a>
<span id="footer_next">&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
Next Topic:&nbsp;&nbsp;<a href=""></a></span>
</p>
<div id="copyrights">
<p><a href="/">Datamapper ORM</a> &nbsp;&middot;&nbsp; Copyright &copy; 2010-2011 &nbsp;&middot;&nbsp; Harro "WanWizard" Verton</p>
<p><a href="license.html">Other License Information</a></p>
</div>
</div>

<script type="text/javascript" src="../js/mootools.js"></script>
<script type="text/javascript" src="../js/menu.js"></script>
<script type="text/javascript">
<!--
	window.addEvent('domready', function() {

		// Create Menu
		var menu = new Menu({
			basepath: '../',
			pagespath: ''
		});

	});
//-->
</script>
</body>
</html>
